/* Copyright 2007-2008 dnAnalytics Project.
 *
 * Contributors to this file:
 * Patrick van der Velde
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 
 * * Redistributions of source code must retain the above copyright notice, this 
 *   list of conditions and the following disclaimer.
 * * Redistributions in binary form must reproduce the above copyright notice, 
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * * Neither the name of the dnAnalytics Project nor the names of its contributors
 *   may be used to endorse or promote products derived from this software without
 *   specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

using System;
using System.Collections.ObjectModel;

namespace dnAnalytics.LinearAlgebra.Solvers
{
    /// <summary>
    /// Defines the base interface for iterators that help control an iterative calculation.
    /// </summary>
    public interface IIterator : ICloneable
    {
        /// <summary>
        /// Adds an <c>IIterationStopCriterium</c> to the internal collection of stop-criteria. Only a 
        /// single stop criterium of each type can be stored.
        /// </summary>
        /// <param name="stopCriterium">The stop criterium to add.</param>
        /// <exception cref="ArgumentNullException">
        ///   Thrown if <paramref name="stopCriterium"/> is null.
        /// </exception>
        /// <exception cref="DuplicateStopCriteriumException">
        ///   Thrown if <paramref name="stopCriterium"/> is of the same type as an already 
        ///   stored criterium.
        /// </exception>
        void Add(IIterationStopCriterium stopCriterium);

        /// <summary>
        /// Removes the <c>IIterationStopCriterium</c> from the internal collection.
        /// </summary>
        /// <param name="stopCriterium">The stop criterium that must be removed.</param>
        void Remove(IIterationStopCriterium stopCriterium);

        /// <summary>
        /// Indicates if the specific stop criterium is stored by the <c>IIterator</c>.
        /// </summary>
        /// <param name="stopCriterium">The stop criterium.</param>
        /// <returns><c>true</c> if the <c>IIterator</c> contains the stop criterium; otherwise <c>false</c>.</returns>
        bool Contains(IIterationStopCriterium stopCriterium);

        /// <summary>
        /// Indicates to the iterator that the iterative process has been cancelled.
        /// </summary>
        /// <remarks>
        /// Does not reset the stop-criteria.
        /// </remarks>
        void IterationCancelled();

        /// <summary>
        /// Determines the status of the iterative calculation based on the stop criteria stored
        /// by the current <c>IIterator</c>.
        /// </summary>
        /// <param name="iterationNumber">The number of iterations that have passed so far.</param>
        /// <param name="solutionVector">The vector containing the current solution values.</param>
        /// <param name="sourceVector">The right hand side vector.</param>
        /// <param name="residualVector">The vector containing the current residual vectors.</param>
        /// <returns>
        ///   An <c>ICalculationStatus</c> which indicates what the status of the iterative 
        ///   calculation is according to the current <c>IIterator</c>.
        /// </returns>
        /// <remarks>
        /// The individual iterators may internally track the progress of the calculation based
        /// on the invocation of this method. Therefore this method should only be called if the 
        /// calculation has moved forwards at least one step.
        /// </remarks>
        void DetermineStatus(int iterationNumber, Vector solutionVector, Vector sourceVector, Vector residualVector);

        /// <summary>
        /// Returns the current calculation status.
        /// </summary>
        /// <remarks>
        /// Note to implementers: <c>null</c> is not a legal value.
        /// </remarks>
        ICalculationStatus Status { get; }

        /// <summary>
        /// Resets the <c>IIterator</c> to the pre-calculation state.
        /// </summary>
        /// <remarks>
        /// Note to implementers: Invoking this method should not clear the user defined
        /// property values, only the state that is used to track the progress of the 
        /// calculation.
        /// </remarks>
        void ResetToPrecalculationState();

        /// <summary>
        /// Creates a deep clone of the current iterator.
        /// </summary>
        /// <returns>The deep clone of the current iterator.</returns>
        new IIterator Clone();
    }
}
